MTRX is a bookkeeping  program for maintaining  a rather simple  electronic
fund transfer system.   It will keep  records on any  number of people  and
allow debts among those people  to be accumulated, automatically  balancing
compensating debts.  (In particular, if FOO owes BAR and BAR owes BAZ, then
MTRX simplifies things to  show that FOO owes  BAZ.)  Complete records  are
maintained of all transactions  and are kept  available for auditing.   The
files used by MTRX are  checksummed in all sorts  of bizarre ways; this  is
primarily to catch disk  errors and the  like.  A determined  trouble-maker
could no doubt evade the double-checks and tweak the files.  Caveat emptor!

MTRX always uses the  files on the logged-in  ppn.  (This prevents  someone
from using MTRX on your files  unless he knows your password, assuming  you
require a local  password on the  directory used for  your matrix.)  If  it
can't find the files it wants, it  assumes this is your first time  running
MTRX from  that  ppn and  offers  to initialise.   Initialisation  involves
creating a  few files  and asking  for a  Master Password  for the  matrix.
(More on passwords later.)  Having  initialised, it will then proceed  with
the normal start-up sequence, as described next.

NORMAL USE OF MTRX

When you start up MTRX, it first  checks (to the best of its ability)  that
all the files are consistent.  Assuming they are, it then asks who you are.
You must  enter the name of  someone already  known to  the program  (i.e.,
someone involved in  a transaction  previously entered  in this  particular
matrix), or  type  null  to  do an  audit.   (The  auditing  functions  are
described later.)  Exception: If no transactions have been entered yet  for
this matrix (i.e., if you have just initialised), then for obvious  reasons
the name you give need not be in the matrix.  However, you will be required
to confirm the "new" name as you would any other new name (see below).

The program will request a password in order to confirm your identity,  and
will then bring you up to date  by listing all transactions that have  been
entered since the last time you entered anything into the matrix.  You will
then enter the main loop.  In this loop, you are to enter new  transactions
by specifying BY WHOM the amount is  owed, TO WHOM the amount is owed,  the
amount (in dollars, with a decimal point if necessary), and a brief  reason
for the debt (up  to 25 characters).  The  transaction is then printed  and
you are asked to confirm  it.  (Affirmative responses to this  confirmation
request are: y, yes, ok, okay, sure, right, check, or unquestionably.   The
word must be  typed in full;  case is unimportant.)   A transaction may  be
aborted at any point  prior to confirmation by  typing a null line.   I.e.,
zero (and negative) amounts are not  allowed, and you must give a  non-null
reason for the debt.  Debts from FOO to FOO are also verboten.  A null line
in response to the BY WHOM question takes you out of the main loop and into
the closeout routine.  Note that transactions are always entered as  debts.
If FOO pays BAR, this is entered as BAR owing FOO.

When you're done entering new transactions and give a null line to get  out
of the main loop, MTRX shows you the updated matrix of debts.  Names  along
the top of the matrix  are those of people who  owe money; names along  the
left are those who are owed.  (This flow of money is indicated by a pair of
arrows in the upper-left-hand corner on display terminals.)  Entries in the
matrix indicate  the amounts  owed.  (Of  course, just  because the  matrix
happens to indicate that  FOO owes BAR doesn't  make much difference.   FOO
could pay  the money  to anybody  whose name  is known  to the  matrix  and
his/her debt would be balanced out.)  The right-hand column and bottom  row
show the totals  owed to  and by  each person.   Having shown  you the  new
matrix, MTRX then asks  if you want  to save the  updated matrix.  SO  FAR,
NONE OF THE  FILES HAVE ACTUALLY  BEEN CHANGED.  The  default is "No",  you
must type something starting with a "Y" (or "y") to save the matrix.  (It's
assumed it's safer to  require that you reenter  a few transactions  should
you blow  it, than  for the  files to  get updated  by accident.)   If  you
decline to save the matrix (MTRX will ask you twice), then all of your  new
transactions will be discarded and you will be logged out.  Otherwise,  the
new files will be saved,  after which you will be  given a chance to  print
one or more copies of the matrix on the line printer, after which you  will
be logged out.  (MTRX' standard exit is via a K/F.)

ADDING PEOPLE TO THE MATRIX

Every once  in a  while a  transaction  will involve  someone who  has  not
previously been involved in the particular matrix.  When this happens,  you
can enter the person's name as usual, but MTRX will object that it  doesn't
know the person, and will list  the people it does know about.   (Actually,
it may not list all the people it knows about.  It tries to decide whom you
actually had in mind,  and lists the most  likely candidates.  E.g., if  it
knows about John, Joe, and Jack, and  you give it Josh, it'll suggest  John
or Joe.)  Anyhow, assuming you really  mean a new person and didn't  simply
mistype an existing  name, you should  then enter the  name a second  time.
The name will be  added to the  list.  You will be  asked for the  person's
full name  (so that  people don't  have to  guess who  s/he is  based on  a
nickname) and for an initial password for the person (which may be  changed
later).  Neither of these may be null.

If the  transaction involving  the new  person is  aborted, the  person  is
flushed from  the list.   If the  transaction goes  through, however,  that
person is entered forever (assuming you save the new matrix when you're all
done).  NO NAME IS EVER FORGOTTEN.   If a person's debt happens to  balance
out to zero, that person  will no longer be  shown in the matrix  printout,
but the name will be remembered forever for the purposes of auditing.   So,
if you ever enter a new name and then decide you didn't mean it, flush  the
transaction!

Note that it  is assumed that  anybody known to  some particular matrix  is
permitted to run MTRX  on that matrix.   If you don't want  this to be  the
case, simply refrain from giving out the login password for that ppn.

THE DUMMY

Every new matrix includes as its first known "name" a special name:  Dummy.
Dummy is not allowed to  run MTRX (i.e., don't  try answering Dummy to  the
"who are you" question at start-up time).  However, it is sometimes  useful
to include Dummy in transactions.  For instance, suppose four people go out
to dinner.  The bill comes  to $65, of which FOO  pays for the drinks  ($7)
and BAR and  BAZ each  pay $29.  Meanwhile,  it's decided  that FOO's  fair
share comes to $16,  BAR's is $16.50,  BAZ's is $15,  and ZOT's is  $17.50.
Rather than work  out who owes  whom how  much, you can  enter this  fairly
easily by pretending that  the people who paid  really gave their money  to
Dummy, who then paid for everything.  Thus Dummy owes $7 to FOO and $29  to
each of BAR and  BAZ, and the  four people owe  Dummy for their  respective
shares of the meal.

MTRX will not allow  you to leave  the main loop if  Dummy's total has  not
balanced out to zero.  This means you  may have to tweak an amount now  and
then to make the  rounding errors work out  right.  (There are no  rounding
errors within MTRX, which always deals internally with integral numbers  of
cents.  But a $10 debt  split 3 ways must be  entered as $3.33, $3.33,  and
$3.34 (if Dummy is involved) to exactly balance the original $10.)

MULTIPLE TRANSACTIONS

In response to either or both of the "BY WHOM" and "TO WHOM" questions, you
may respond with a list of names, separated by any non-alphabetics.   E.g.,
you may say that "John, Joe, & Fred" owe "George/Jack".   In this  example,
this would be a total of six transactions: each of the debtors owes each of
the creditors the specified amount.  If what  you want is for the TOTAL  of
the debts to be a certain amount, give the amount suffixed with an "S" (for
"split" or "share"), and the amount will be divided by the total number  of
transactions (and rounded to the nearest cent).

The lists of names may  include new names as usual;  each new name will  be
questioned separately.  If, when questioned about an unknown name, you type
a null line, that name will be ignored but the rest of the list will  still
be processed.

If either list contains more than  one name, then MTRX permits  self-debts.
This is to allow such  things as "FOO & BAR"  owing "BAR" a Shared  amount,
which is a handy way to enter a transaction where FOO and BAR are splitting
the cost of something for which  BAR paid.  The "BAR owes BAR"  transaction
will not actually be entered into the audit records.

RANDOM HANDY HACKS

The special name "me" is  taken to mean whoever  is running MTRX; that  is,
whatever name was given at start-up.  This is not allowed when auditing.

The special string "ditto" (case of letters is ignored), when given as  the
explanation for a transaction,  tells MTRX to use  the same explanation  as
the most recent CONFIRMED transaction during this session.  (If this is the
first entry this session, tough beans.)

The special  name  "everybody" (or  "everyone")  is recognised  by  certain
commands in Audit mode (see below), with the obvious interpretation.

In case the line printer  isn't working, you can  respond to a question  of
the form "How many lpt  copies" with a negative  number, in which case  the
absolute value is taken to be the number of XGP copies to print.

AUDITING

If a null name is  given at start-up, MTRX  enters its "audit" mode.   Most
operations in this mode are read-only, but a few cause the matrix files  to
be updated.  As always, the updating is never done until you actually exit.

Audit mode is  about the only  place where MTRX  offers any run-time  help.
You can type ? to review the list of options.  The options are:
	Audit   (print selected record entries)
	Matrix  (print current matrix)
	Totals  (print totals owed by/to selected people)
	Check	(compute totals according to RCD files)
	Names   (print full names of selected people)
	When	(print when selected people last added anything)
	Passwd  (change passwords)
	Flush	(make person inactive--must know password)
	Rename  (change full names)
	Break   (break latest RCD file into two files)
	<cr>    (empty line, causes exit)
Commands may be abbreviated to their first letters.

The  Audit  command  requests  a  pair  of  dates  using  a  fairly   hairy
date-parsing routine.  It will print what it thinks you want as a date  and
tell you to type <cr> or a different date.  It assumes reasonable  defaults
for omitted  months,  years, days,  etc.,  and  tries hard  to  accept  any
ordering (3-May-77 vs. 77-May-03 etc.) and so on.  (Good luck with  3/5/77,
though: it's taken to be March 5.)  Days of the week and special hacks like
"yesterday" are NOT accepted.  Anyhow, having specified two dates, you then
specify a  list of  names, and  MTRX provides  a list  of all  transactions
involving any of those people within  that range of dates.  (This does  not
include all transactions ENTERED by those people.)  You're given the option
of listing the information on your terminal or spooling one or more copies.

The Matrix option similarly gives you the option of printing vs. spooling.

The Totals  option computes  its results  using the  current matrix  data,
whereas  the  Check  option  actually  goes  back  over  the  records  and
recomputes what the totals should be.  If you specify a range of RCD files
(see below)  which includes  the  most recent  one,  then the  totals  are
compared against the current matrix.   If there are any differences,  then
it is assumed that  there are earlier records  which were not included  in
the range, and MTRX reports what the totals SHOULD HAVE BEEN as of the end
of those earlier records.   (Hence, before deleting an  old RCD file,  you
should do a Check of that file and note somewhere what the totals actually
were.)  If what the totals should have been does not match what they were,
(especially if all RCD files still exist and are included in the range  of
the Check), then something  is wrong; probably  someone has tampered  with
the RCD files.

The Passwd option asks first  for the NEW password,  then for the OLD  one.
This lets you abort the change (for  instance, if you're not sure what  you
typed as the new password (echoing is of course turned off)) by failing  to
give the old password correctly.  The  new password is requested twice;  if
the two inputs fail to match the operation is aborted.  The "old  password"
may also be the  Master Password; i.e., whoever  knows the Master  Password
can change ANY password.  The only way to change the Master Password is  to
know what it currently is.  (The Master Password is that of Dummy.)

When a person  is flushed,  it means  that the  person doesn't  want to  be
included in the matrix  any more.  The  person must have  a zero total.   A
person who is flushed  is no longer  permitted to run  the matrix, and  any
transaction involving him/her will require  giving the name twice, just  as
for a new person entering the matrix.   If such a transaction is made,  the
person is restored to active status and may once again run the matrix.   It
is intended that people flush themselves; hence one must know the  password
(or the Master Password) to flush a person.  Note that the person's name is
not forgotten; it is remembered for  the purposes of auditing, and will  be
included as part of "everyone" where applicable.

The Rename  and Break  options  require the  Master Password.   The  latter
option is described below in the section on files.

The other options should be fairly self-explanatory.

MATRIX FILES

The MTRX program uses the following files:  MATRIX.DAT contains the current
matrix for the ppn.  It  also contains people's names, passwords  (hashed),
how much they've seen, etc.  The only  other files used are *.RCD, where  *
is a positive  number right-justified, starting  with ↓_____1↓.RCD.   These
contain the audit records,  and one of  the double-checks performed  during
start-up is that the existing RCD files must form a contiguous chunk.

There is no backup other than that normally provided via DART.

Whenever you save a new  matrix, MTRX must write  out a new MATRIX.DAT  and
also recopy the  most recent RCD  file (it doesn't  append with  Read-Alter
mode because that might leave the file partially updated in the event of  a
crash).  Hence it pays  not to let  the latest RCD file  get too big  (say,
more than two disk tracks).  When a RCD file gets big enough, you can split
it up into two files using the Break audit option.  (This requires that you
know the Master Password.)  Only the most recent file can be split, and  it
must be split at a  date boundary.  Neither of  the new files thus  created
may be empty.  Having split  a RCD file, you are  not required to keep  the
older half on disk (unless you have a still older RCD file lying around; in
general, you can always delete the oldest RCD file unless there's only  one
left); it is  recommended that  you wait  for it to  be backed  up by  DART
and also do a Check (see above) on it before deleting it.

The "standard" way to set up a matrix is to dedicate a directory to it, and
give out the password for that directory to all people who are known to the
matrix.  If this is done, then a suggested OPTION.TXT file is:

login:fdm,who,nomail,hide,qmaint,xmail,nonote,run=mtrx;

A suggested directory protection is 077, default file protection 000.

LIMITS AND RESTRICTIONS

There are a few arbitrary limits built into MTRX.  The first two limits can
be expanded if anybody  asks (send a  note to DON).   The others cannot  be
changed without making all old matrix files invalid.

No more than 15 people can be "active" in the matrix at any time.   (People
whose totals are zero are inactive.)  People whose totals have gone to zero
during the current session remain active  until the end of the session,  so
if you  hit this  limit it  may pay  to finish  the session,  save the  new
matrix, then start up again and try again.

No more than 30 names may be known the program.  Remember that a name, once
known, is never forgotten.  This same limit is the maximum number of  names
you can give when asked for a list of names, such as "Owed by whom" or  one
of the audit functions.

The explanation field of a transaction is truncated at 25 characters.

The "full name" of a person may  be of unlimited length (but must be  typed
on a single line).

Passwords may not  be null.   They may  be of  any length  (only the  first
hundred or so  characters will  be significant).   Case of  letters is  not
significant in a password (just like everywhere else).

The "short" name of a person may be of any length, but it's best to keep it
fairly short; say no more than 5-7 characters.  Some printout will truncate
the names to 5 or 6 characters; others will pad all names to the length  of
the longest one in the particular output.

No more than one person  may manipulate any given  matrix at any one  time.
(The MTRX program interlocks against this by not allowing itself to be  run
by more than one person on any given ppn.)